home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / OpenGL / glcopytexsubimage2d.z / glcopytexsubimage2d
Encoding:
Text File  |  2002-10-03  |  17.3 KB  |  266 lines
  1.  
  2.  
  3.  
  4. ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))        OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee        ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD - copy a two-dimensional texture subimage
  10.  
  11.  
  12. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      void ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD( GLenum _t_a_r_g_e_t,
  14.                                GLint _l_e_v_e_l,
  15.                                GLint _x_o_f_f_s_e_t,
  16.                                GLint _y_o_f_f_s_e_t,
  17.                                GLint _x,
  18.                                GLint _y,
  19.                                GLsizei _w_i_d_t_h,
  20.                                GLsizei _h_e_i_g_h_t )
  21.  
  22.  
  23. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  24.      _t_a_r_g_e_t   Specifies the target texture.  Must be GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____2222DDDD.
  25.  
  26.      _l_e_v_e_l    Specifies the level-of-detail number.  Level 0 is the base image
  27.               level.  Level _n is the _nth mipmap reduction image.
  28.  
  29.      _x_o_f_f_s_e_t  Specifies a texel offset in the x direction within the texture
  30.               array.
  31.  
  32.      _y_o_f_f_s_e_t  Specifies a texel offset in the y direction within the texture
  33.               array.
  34.  
  35.      _x, _y     Specify the window coordinates of the lower left corner of the
  36.               rectangular region of pixels to be copied.
  37.  
  38.      _w_i_d_t_h    Specifies the width of the texture subimage.
  39.  
  40.      _h_e_i_g_h_t   Specifies the height of the texture subimage.
  41.  
  42. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  43.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD replaces a rectangular portion of a two-dimensional
  44.      texture image with pixels from the current GGGGLLLL____RRRREEEEAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRR (rather than
  45.      from main memory, as is the case for ggggllllTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD).
  46.  
  47.      The screen-aligned pixel rectangle with lower left corner at (_x, _y) and
  48.      with width _w_i_d_t_h and height _h_e_i_g_h_t replaces the portion of the texture
  49.      array with x indices _x_o_f_f_s_e_t through _x_o_f_f_s_e_t + _w_i_d_t_h - 1, inclusive, and
  50.      y indices _y_o_f_f_s_e_t through _y_o_f_f_s_e_t + _h_e_i_g_h_t - 1, inclusive, at the mipmap
  51.      level specified by _l_e_v_e_l.
  52.  
  53.      The pixels in the rectangle are processed exactly as if ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss had
  54.      been called, but the process stops just before final conversion.  At this
  55.      point, all pixel component values are clamped to the range [0, 1] and
  56.      then converted to the texture's internal format for storage in the texel
  57.      array.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))        OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee        ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      The destination rectangle in the texture array may not include any texels
  75.      outside the texture array as it was originally specified.  It is not an
  76.      error to specify a subtexture with zero width or height, but such a
  77.      specification has no effect.
  78.  
  79.      If any of the pixels within the specified rectangle of the current
  80.      GGGGLLLL____RRRREEEEAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRR are outside the read window associated with the current
  81.      rendering context, then the values obtained for those pixels are
  82.      undefined.
  83.  
  84.      No change is made to the _i_n_t_e_r_n_a_l_f_o_r_m_a_t, _w_i_d_t_h, _h_e_i_g_h_t, or _b_o_r_d_e_r
  85.      parameters of the specified texture array or to texel values outside the
  86.      specified subregion.
  87.  
  88. NNNNOOOOTTTTEEEESSSS
  89.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD is available only if the GL version is 1.1 or
  90.      greater.
  91.  
  92.      Texturing has no effect in color index mode.
  93.  
  94.      ggggllllPPPPiiiixxxxeeeellllSSSSttttoooorrrreeee and ggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr modes affect texture images in exactly
  95.      the way they affect ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss.
  96.  
  97.      When the GGGGLLLL____AAAARRRRBBBB____iiiimmmmaaaaggggiiiinnnngggg extension is supported, the RGBA components read
  98.      from the framebuffer may be processed by the imaging pipeline.  See
  99.      ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD for specific details.
  100.  
  101. EEEERRRRRRRROOOORRRRSSSS
  102.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is generated if _t_a_r_g_e_t is not GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____2222DDDD.
  103.  
  104.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if the texture array has not been
  105.      defined by a previous ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD or ggggllllCCCCooooppppyyyyTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD operation.
  106.  
  107.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated if _l_e_v_e_l is less than 0.
  108.  
  109.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE may be generated if _l_e_v_e_l is greater than log max, where
  110.                                                                    2
  111.      max is the returned value of GGGGLLLL____MMMMAAAAXXXX____TTTTEEEEXXXXTTTTUUUURRRREEEE____SSSSIIIIZZZZEEEE.
  112.  
  113.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated if _x <  -b or if _y <  -b, where b is the
  114.      border width of the texture array.
  115.  
  116.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated if xoffset < -b,
  117.      (_x_o_f_f_s_e_t + _w_i_d_t_h) > (w - b), _y_o_f_f_s_e_t <  -b, or
  118.      (_y_o_f_f_s_e_t + _h_e_i_g_h_t) > (h - b), where w is the GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____WWWWIIIIDDDDTTTTHHHH, h is the
  119.      GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____HHHHEEEEIIIIGGGGHHHHTTTT, and b is the GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____BBBBOOOORRRRDDDDEEEERRRR of the texture image
  120.      being modified.  Note that w and h include twice the border width.
  121.  
  122.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD is executed
  123.      between the execution of ggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of
  124.      ggggllllEEEEnnnndddd.
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                         PPPPaaaaggggeeee 2222
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137. ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))        OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee        ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))
  138.  
  139.  
  140.  
  141. AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD GGGGEEEETTTTSSSS
  142.      ggggllllGGGGeeeettttTTTTeeeexxxxIIIImmmmaaaaggggeeee
  143.      ggggllllIIIIssssEEEEnnnnaaaabbbblllleeeedddd with argument GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____2222DDDD
  144.  
  145.  
  146. MMMMAAAACCCCHHHHIIIINNNNEEEE DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS
  147.      RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems do not support color
  148.      matrix transformations on images as they are loaded to or read back from
  149.      texture memory.
  150.  
  151.      RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems support
  152.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD and ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDDEEEEXXXXTTTT with the following
  153.      restrictions:
  154.  
  155.           1.  Only level 0 is supported; other levels result in a
  156.               GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE error.
  157.  
  158.           2.  The texel offsets and the dimensions of the subimage must be
  159.               multiples of 32; otherwise a GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE error is
  160.               generated.
  161.  
  162.           3.  If ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD or ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDDEEEEXXXXTTTT is used when a
  163.               GLX video source is the read drawable (see
  164.               ggggllllXXXXMMMMaaaakkkkeeeeCCCCuuuurrrrrrrreeeennnnttttRRRReeeeaaaaddddSSSSGGGGIIII), the X offset and Y offset must both be 0
  165.               and the subimage width must be 768; otherwise a GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE
  166.               error is generated.
  167.  
  168.           4.  GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____SSSSGGGGIIIIXXXX is not supported (see ggggllllEEEEnnnnaaaabbbblllleeee).
  169.  
  170.      On IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy systems, there is a performance benefit when the width
  171.      of the image to be transferred to texture memory is a multiple of 8.
  172.  
  173.      Texture borders are not supported on IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy systems.
  174.      Applications should use borderless textures and GGGGLLLL____CCCCLLLLAAAAMMMMPPPP____TTTTOOOO____EEEEDDDDGGGGEEEE____SSSSGGGGIIIISSSS
  175.      wrap mode.
  176.  
  177.      On HHHHiiiigggghhhh IIIImmmmppppaaaacccctttt and MMMMaaaaxxxxiiiimmmmuuuummmm IIIImmmmppppaaaacccctttt systems, if the right side of the image
  178.      to be transferred to texture memory is not the right side of the texture,
  179.      then its index must be a multiple of 32, where index = xoffset+width.
  180.      Otherwise it will generate a GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE error.
  181.  
  182.      The SSSSGGGGIIIIXXXX____iiiinnnntttteeeerrrrllllaaaacccceeee extension is supported only on IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy
  183.      systems, on RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems, on OOOOccccttttaaaannnneeee2222
  184.      VVVVPPPPrrrroooo systems, and on OOOO2222 systems.
  185.  
  186.      The IIIINNNNGGGGRRRR____iiiinnnntttteeeerrrrllllaaaacccceeee____rrrreeeeaaaadddd extension is supported only on OOOOccccttttaaaannnneeee2222 VVVVPPPPrrrroooo
  187.      systems, and on OOOO2222 systems.
  188.  
  189.      On OOOO2222 systems, when the current _r_e_a_d drawable is a DM pbuffer, using
  190.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD or ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDDEEEEXXXXTTTT to copy into a full texture
  191.      image whose dimensions and format match those of the pbuffer causes a
  192.      copy-by-reference.  This has performance advantages, especially for
  193.  
  194.  
  195.  
  196.                                                                         PPPPaaaaggggeeee 3333
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203. ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))        OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee        ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD((((3333GGGG))))
  204.  
  205.  
  206.  
  207.      video-generated DMbuffers, because it provides a DMA path for updating
  208.      textures.  Following the copy, rendering to the pbuffer or otherwise
  209.      modifying the DMbuffer, will directly affect texture memory.  However,
  210.      this behavior is essentially an unspecified side-effect of the
  211.      implementation on OOOO2222, and cannot be used on other systems.
  212.  
  213.  
  214. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  215.      ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss, ggggllllCCCCooooppppyyyyTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD, ggggllllCCCCooooppppyyyyTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD, ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee1111DDDD,
  216.      ggggllllCCCCooooppppyyyyTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee3333DDDD, ggggllllPPPPiiiixxxxeeeellllSSSSttttoooorrrreeee, ggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr, ggggllllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrr,
  217.      ggggllllTTTTeeeexxxxEEEEnnnnvvvv, ggggllllTTTTeeeexxxxGGGGeeeennnn, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee3333DDDD,
  218.      ggggllllTTTTeeeexxxxPPPPaaaarrrraaaammmmeeeetttteeeerrrr, ggggllllTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee1111DDDD, ggggllllTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee2222DDDD, ggggllllTTTTeeeexxxxSSSSuuuubbbbIIIImmmmaaaaggggeeee3333DDDD
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                                                                         PPPPaaaaggggeeee 4444
  263.  
  264.  
  265.  
  266.